package com.wg.core.script;

/**
 * 脚本接口，定义脚本的生命周期和执行规范
 * <p>
 * 实现类需注意：
 * </p>
 * <ul>
 * <li>init() 和 destroy() 可能在多线程环境调用，必须保证线程安全</li>
 * <li>call() 方法可能被并发调用，需根据业务确保线程安全（建议无状态设计）</li>
 * <li>脚本执行结果建议使用具体类型而非Object，便于调用方处理</li>
 * </ul>
 *
 * @author ChenLong
 */
public interface IScript {

    /**
     * 脚本初始化（首次加载或重载后调用）
     * <p>
     * 用于初始化资源（如配置加载、缓存预热等），需保证线程安全
     * </p>
     */
    void init();

    /**
     * 脚本销毁（重载前或程序退出时调用）
     * <p>
     * 用于释放资源（如数据库连接、IO流、定时器等），需保证线程安全
     * </p>
     */
    void destroy();

    /**
     * 执行脚本核心逻辑
     *
     * @param scriptName 脚本全类名（用于日志追踪和问题定位）
     * @param arg        类型安全的参数容器（不可为null）
     * @return 执行结果（建议返回具体业务类型，避免Object强转）
     * @throws Exception 执行异常（由调用方统一处理，需包含业务错误信息）
     */
    Object call(String scriptName, ScriptArgs arg) throws Exception;
}